home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 August: Tool Chest / Dev.CD Aug 98 TC.toast / Tool Chest / Testing & Debugging / Virtual User / Virtual User Current Release / Supplements / Assist Module for MacApp / Assist Module MA 3.0 / READ ME FIRST!
Encoding:
Text File  |  1998-06-04  |  7.6 KB  |  192 lines  |  [TEXT/MPS ]
  1. **************************************************************************
  2. What is VUAssist?
  3. **************************************************************************
  4. The code contained in this folder is the source code for a MacApp 3.0
  5. compatible version of VUAssist.  VUAssist is a Virtual User assistance module
  6. for MacApp applications.  By building VUAssist into your MacApp application, 
  7. you will be able to manipulate the user interface of your application very 
  8. easily with Virtual User.  
  9.  
  10.  
  11. Technical Background
  12. --------- ----------
  13. In order to find the location of items in windows for V.U., Agent VU peruses 
  14. the content list of windows and the item list of dialogs.  For applications 
  15. which are not built with MacApp, these data structures can be accessed via 
  16. global variables by Agent VU.  For MacApp applications, however, items in 
  17. windows are subclasses of the class TView, which are not available to the 
  18. Agent via global data structures.   As a result, Agent VU can’t provide any 
  19. information about these items to V.U. in the normal way.
  20.  
  21. To work around this problem, Agent VU provides a hook which allows an 
  22. application to assist Agent VU by providing information about itself.  
  23. In this folder, we’ve provided VUAssist, an assistance module for MacApp 
  24. applications which can be hooked onto Agent VU to provide information about 
  25. a MacApp application. A developer can build a MacApp application with VUAssist 
  26. and then test the application with V.U..  V.U. will "recognize" many of the
  27. application's views which translate into standard user interface items: buttons,
  28. scroll bars, checkboxes, static text, editable text fields, popup menus, etc.
  29.  
  30.  
  31. The module exists as a unit called UVUAssist.  The unit consists of four files:   
  32. UVUAssist.p, UVUAssist.inc1.p, UVUAssist.inc2.p, and UVUAssist.a.
  33.  
  34.  
  35. -----------------------------------------------------------------------------
  36. What's New in this Version - 1.0a2
  37. -----------------------------------------------------------------------------
  38. ******** Changes relative to the 1.0a1 version ********  
  39.  
  40. 1) A problem with getting information about TPopup descendants on a target
  41. running System 7.1 has been fixed.  
  42.  
  43. 2) A problem with the reporting of control type (button instead of radiobutton
  44. or checkbox) when running in 32-bit addressing mode has been fixed.
  45.  
  46. -----------------------------------------------------------------------------
  47. How to Use VUAssist
  48. -----------------------------------------------------------------------------
  49.  
  50. To build VUAssist into your MacApp application, follow the instructions
  51. below.  
  52.  
  53. For applications written in Object Pascal:
  54.  
  55. 1)  Modify your MAMake file to include the following:
  56.  
  57.     •    add the following to the list of OtherInterfaces
  58.         
  59.         "{SrcApp}UVUAssist.p"
  60.         
  61.     •    add the following to the list of OtherLinkFiles
  62.         
  63.         "{ObjApp}UVUAssist.a.o" ∂
  64.         "{ObjApp}UVUAssist.p.o" 
  65.     
  66.     •    add the additional dependencies:
  67.  
  68.         "{ObjApp}UVUAssist.p.o"    ƒ ∂
  69.                     "{SrcApp}UVUAssist.p" ∂
  70.                     "{SrcApp}UVUAssist.inc1.p" ∂
  71.                     "{SrcApp}UVUAssist.inc2.p" ∂
  72.                     {MacAppIntf} ∂
  73.                     {BuildingBlocksIntf}
  74.                     
  75.         "{ObjApp}UVUAssist.a.o"    ƒ ∂
  76.                             "{SrcApp}UVUAssist.a" 
  77.                             
  78. 2)     Modify or subclass your descendant of TApplication to do the following:
  79.                             
  80.     •    In MyApplication.IApplication, you must execute this:
  81.             NEW(gVUAssist);
  82.             gVUAssist.IVUAssist(gridItemSupport); { gridItemSupport must be a boolean expression.
  83.                                                     see "Altering the behavior of VUAssist
  84.                                                     for an explanation of gridItemSupport }
  85.             gVUAssist.SetIdleFreq(kVUAssistIdleFreq);
  86.             SELF.InstallCohandler(gVUAssist,true);
  87.             
  88.     •    In MyApplication.AboutToLoseControl you must execute this:
  89.             gVUAssist.SuspendMole;
  90.  
  91.     •    In MyApplication.RegainControl you must execute this:
  92.             gVUAssist.ResumeMole;
  93.  
  94.     •    In MyApplication.Close you must execute this BEFORE calling INHERITED Close:
  95.             SELF.InstallCohandler(gVUAssist,false);
  96.  
  97. 3)    Include the unit UVUAssist in your USES clause where appropriate.  Other units may 
  98.     need to be included along with UVUAssist if they are not already.
  99.  
  100.  
  101. For applications written in C++:
  102.  
  103. 1)  Modify your MAMake file to include the following:
  104.  
  105.     •    add the following to the list of OtherInterfaces
  106.         
  107.         "{SrcApp}UVUAssist.h"
  108.         
  109.     •    add the following to the list of OtherLinkFiles
  110.         
  111.         "{ObjApp}UVUAssist.a.o" ∂
  112.         "{ObjApp}UVUAssist.p.o" 
  113.     
  114.     •    add the additional dependencies:
  115.  
  116.         "{ObjApp}UVUAssist.p.o"    ƒ ∂
  117.                     "{SrcApp}UVUAssist.p" ∂
  118.                     "{SrcApp}UVUAssist.inc1.p" ∂
  119.                     "{SrcApp}UVUAssist.inc2.p" ∂
  120.                     {MacAppIntf} ∂
  121.                     {BuildingBlocksIntf}
  122.                     
  123.         "{ObjApp}UVUAssist.a.o"    ƒ ∂
  124.                             "{SrcApp}UVUAssist.a" 
  125.                             
  126. 2)     Modify or subclass your descendant of TApplication to do the following:
  127.                             
  128.     •    In MyApplication.IApplication, you must execute this:
  129.             gVUAssist = new TVUAssist;
  130.             gVUAssist->IVUAssist(gridItemSupport); /* gridItemSupport must be a boolean expression.
  131.                                                       see "Altering the behavior of VUAssist
  132.                                                       for an explanation of gridItemSupport */
  133.             gVUAssist->SetIdleFreq(kVUAssistIdleFreq);
  134.             this->InstallCohandler(gVUAssist, TRUE);
  135.             
  136.     •    In MyApplication.AboutToLoseControl you must execute this:
  137.             gVUAssist->SuspendMole();
  138.  
  139.     •    In MyApplication.RegainControl you must execute this:
  140.             gVUAssist->ResumeMole();
  141.  
  142.     •    In MyApplication.Close you must execute this BEFORE calling INHERITED Close:
  143.             this->InstallCohandler(gVUAssist,false);
  144.  
  145. 3)    Include the header file UVUAssist.h where appropriate.
  146.  
  147.         #ifndef __UVUASSIST__
  148.         #include "UVUAssist.h"
  149.         #endif
  150.  
  151. 4)    If you are using C++, make sure to use the VUAssist.a file which is included in the 
  152.     folder "C++ Interface to VUAssist" in place of the file with the same name which is 
  153.     found in the folder "VUAssist Source Code".
  154.  
  155.  
  156. -----------------------------------------------------------------------------
  157. Modifying the Behavior of VUAssist
  158. -----------------------------------------------------------------------------
  159.  
  160. 1) VUAssist Idle Frequency
  161.  
  162. VUAssist has now been defined to be a descendant TEventHandler.  An application's 
  163. responsiveness to V.U. queries can be controlled by setting the idle frequency of 
  164. VUAssist. Although nothing is done with this idle time, it forces the application to 
  165. awaken and call SystemTask with the application's context switched in.  This is necessary 
  166. for Agent VU, a driver, to get processing time.  Agent VU, in turn, calls VUAssist.  
  167. So, in a roundabout way, the application's responsiveness to V.U. can be controlled by 
  168. setting the idle frequency of VUAssist.
  169.  
  170. The default idle frequency is kVUAssistIdleFreq, which is set to 1.  You may want to alter 
  171. this by executing the following statement:
  172.  
  173.     gVUAssist.SetIdleFreq(newIdleFreq);
  174.  
  175. Note, however, that larger values of VUAssist's idle frequency will slow down the application's
  176. response to V.U. unless there is another cohandler with a very high idle frequency.
  177.  
  178.  
  179. 2) The gridItemSupport Argument
  180.  
  181. Note that the TVUAssist method IVUAssist now takes an argument, gridItemSupport.  This
  182. argument, if true, enables an optional feature of VUAssist where the cells of gridviews are
  183. recognized as individual user interface items by V.U..  Virtual User does not yet have a 
  184. gridview or list descriptor.  So, for the short term, the "gridItemSupport" feature treats
  185. each cell of a gridview as a "contentitem" in the V.U. scripting language.
  186.  
  187. In applications with very large gridviews, it may not be desirable to treat each cell in a
  188. gridview as a separate item in V.U..  This may severely hamper performance.  By setting the 
  189. value of the gridItemSupport argument to false, you will disable V.U.'s griditem support 
  190. feature and the cells of gridviews will not be seen as "contentItems" by V.U..  The cells will 
  191. be "invisible" to Virtual User.
  192.